<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
 <head>
  <meta http-equiv="content-type" content="text/html; charset=UTF-8">
  <title>Runkit Sandbox Class -- PHP Virtual Machine</title>

 </head>
 <body><div class="manualnavbar" style="text-align: center;">
 <div class="prev" style="text-align: left; float: left;"><a href="ref.runkit.html">runkit 函数</a></div>
 <div class="next" style="text-align: right; float: right;"><a href="runkit.sandbox-parent.html">Runkit_Sandbox_Parent</a></div>
 <div class="up"><a href="ref.runkit.html">runkit 函数</a></div>
 <div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="runkit.sandbox" class="refentry">
 <div class="refnamediv">
  <h1 class="refname">Runkit_Sandbox</h1>
  <p class="verinfo">(PECL runkit &gt;= 0.7.0)</p><p class="refpurpose"><span class="refname">Runkit_Sandbox</span> &mdash; <span class="dc-title">
   Runkit Sandbox Class -- PHP Virtual Machine
  </span></p>

 </div>
 <div class="refsect1 description" id="refsect1-runkit.sandbox-description">
  <h3 class="title">说明</h3>

  <p class="para">
   Instantiating the <strong class="classname">Runkit_Sandbox</strong>
   class creates a new thread with its own scope
   and program stack.  Using a set of options passed to the constructor, this environment
   may be restricted to a subset of what the primary interpreter can do and provide a
   safer environment for executing user supplied code.
  </p>

  <blockquote class="note"><p><strong class="note">Note</strong>: <span class="simpara">沙箱支持（是 <span class="function"><a href="function.runkit-lint.html" class="function">runkit_lint()</a></span>，<span class="function"><a href="function.runkit-lint-file.html" class="function">runkit_lint_file()</a></span>
函数，与 <strong class="classname">Runkit_Sandbox</strong> 类所必需）仅可用于
PHP 5.1.0 或 PHP 5.0 的特别修补版本，并需启用线程安全。更多信息可参见 runkit 包中的
<var class="filename">README</var> 文件。</span></p></blockquote>
 </div>


 <div class="refsect1 constructor" id="refsect1-runkit.sandbox-constructor">
  <h3 class="title">Constructor</h3>
  <div class="methodsynopsis dc-description">
   <span class="type"><span class="type void">void</span></span> <span class="methodname"><strong>Runkit_Sandbox::__construct</strong></span>
    ([ <span class="methodparam"><span class="type">array</span> <code class="parameter">$options</code></span>
  ] )</div>


  <p class="para rdfs-comment">
   <em><code class="parameter">options</code></em> is an associative array containing
   any combination of the special ini options listed below.
  </p>

  <p class="para">
   <dl>

    
     <dt>
<em><code class="parameter">safe_mode</code></em></dt>

     <dd>

      <p class="para">
       If the outer script which is instantiating the
       <strong class="classname">Runkit_Sandbox</strong> class
       is configured with <em>safe_mode = off</em>, then safe_mode
       may be turned on for the sandbox environment.  This setting can not
       be used to disable <em>safe_mode</em> when it&#039;s already
       enabled in the outer script.
      </p>
     </dd>

    
    
     <dt>
<em><code class="parameter">safe_mode_gid</code></em></dt>

     <dd>

      <p class="para">
       If the outer script which is instantiating the
       <strong class="classname">Runkit_Sandbox</strong> class
       is configured with <em>safe_mode_gid = on</em>, then safe_mode_gid
       may be turned off for the sandbox environment.  This setting can not
       be used to enable <em>safe_mode_gid</em> when it&#039;s already
       disabled in the outer script.
      </p>
     </dd>

    
    
     <dt>
<em><code class="parameter">safe_mode_include_dir</code></em></dt>

     <dd>

      <p class="para">
       If the outer script which is instantiating the
       <strong class="classname">Runkit_Sandbox</strong> class
       is configured with a <em>safe_mode_include_dir</em>,
       then a new safe_mode_include_dir may be set for sandbox environments
       below the currently defined value.  safe_mode_include_dir may also be
       cleared to indicate that the bypass feature is disabled.
       If safe_mode_include_dir was blank in the outer script, but safe_mode
       was not enabled, then any arbitrary safe_mode_include_dir may be set
       while turning safe_mode on.
      </p>
     </dd>

    
    
     <dt>
<em><code class="parameter">open_basedir</code></em></dt>

     <dd>

      <p class="para">
       <em><code class="parameter">open_basedir</code></em> may be set to any path below the
       current setting of <em>open_basedir</em>. If
       <em>open_basedir</em> is not set within the global scope,
       then it is assumed to be the root directory and may be set to any location.
      </p>
     </dd>

    
    
     <dt>
<em><code class="parameter">allow_url_fopen</code></em></dt>

     <dd>

      <p class="para">
       Like <em><code class="parameter">safe_mode</code></em>, this setting can only be made more restrictive,
       in this case by setting it to <strong><code>FALSE</code></strong> when it is previously set to <strong><code>TRUE</code></strong>
      </p>
     </dd>

    
    
     <dt>
<em><code class="parameter">disable_functions</code></em></dt>

     <dd>

      <p class="para">
       Comma separated list of functions to disable within the sandbox sub-interpreter.
       This list need not contain the names of the currently disabled functions,
       they will remain disabled whether listed here or not.
      </p>
     </dd>

    
    
     <dt>
<em><code class="parameter">disable_classes</code></em></dt>

     <dd>

      <p class="para">
       Comma separated list of classes to disable within the sandbox sub-interpreter.
       This list need not contain the names of the currently disabled classes,
       they will remain disabled whether listed here or not.
      </p>
     </dd>

    
    
     <dt>
<em><code class="parameter">runkit.superglobal</code></em></dt>

     <dd>

      <p class="para">
       Comma separated list of variables to be treated as superglobals within the
       sandbox sub-interpreter.  These variables will be used in addition to any
       variables defined internally or through the global runkit.superglobal setting.
      </p>
     </dd>

    
    
     <dt>
<em><code class="parameter">runkit.internal_override</code></em></dt>

     <dd>

      <p class="para">
       Ini option <em>runkit.internal_override</em> may be disabled
       (but not re-enabled) within sandboxes.
      </p>
     </dd>

    
   </dl>

  </p>

  <div class="example" id="example-502">
   <p><strong>Example #1 Instantiating a restricted sandbox</strong></p>
   <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br />$options&nbsp;</span><span style="color: #007700">=&nbsp;array(<br />&nbsp;&nbsp;</span><span style="color: #DD0000">'safe_mode'</span><span style="color: #007700">=&gt;</span><span style="color: #0000BB">true</span><span style="color: #007700">,<br />&nbsp;&nbsp;</span><span style="color: #DD0000">'open_basedir'</span><span style="color: #007700">=&gt;</span><span style="color: #DD0000">'/var/www/users/jdoe/'</span><span style="color: #007700">,<br />&nbsp;&nbsp;</span><span style="color: #DD0000">'allow_url_fopen'</span><span style="color: #007700">=&gt;</span><span style="color: #DD0000">'false'</span><span style="color: #007700">,<br />&nbsp;&nbsp;</span><span style="color: #DD0000">'disable_functions'</span><span style="color: #007700">=&gt;</span><span style="color: #DD0000">'exec,shell_exec,passthru,system'</span><span style="color: #007700">,<br />&nbsp;&nbsp;</span><span style="color: #DD0000">'disable_classes'</span><span style="color: #007700">=&gt;</span><span style="color: #DD0000">'myAppClass'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$sandbox&nbsp;</span><span style="color: #007700">=&nbsp;new&nbsp;</span><span style="color: #0000BB">Runkit_Sandbox</span><span style="color: #007700">(</span><span style="color: #0000BB">$options</span><span style="color: #007700">);<br /></span><span style="color: #FF8000">/*&nbsp;Non-protected&nbsp;ini&nbsp;settings&nbsp;may&nbsp;set&nbsp;normally&nbsp;*/<br /></span><span style="color: #0000BB">$sandbox</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">ini_set</span><span style="color: #007700">(</span><span style="color: #DD0000">'html_errors'</span><span style="color: #007700">,</span><span style="color: #0000BB">true</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
   </div>

  </div>
 </div>


 <div class="refsect1 variables" id="refsect1-runkit.sandbox-variables">
  <h3 class="title">Accessing Variables</h3>
  <p class="para">
   All variables in the global scope of the sandbox environment
   are accessible as properties of the sandbox object.
   The first thing to note is that because of the way memory
   between these two threads is managed, object and resource
   variables can not currently be exchanged between interpreters.
   Additionally, all arrays are deep copied and any references
   will be lost.  This also means that references between
   interpreters are not possible.
  </p>

  <div class="example" id="example-503">
   <p><strong>Example #2 Working with variables in a sandbox</strong></p>
   <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br />$sandbox&nbsp;</span><span style="color: #007700">=&nbsp;new&nbsp;</span><span style="color: #0000BB">Runkit_Sandbox</span><span style="color: #007700">();<br /><br /></span><span style="color: #0000BB">$sandbox</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">foo&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #DD0000">'bar'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$sandbox</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">eval</span><span style="color: #007700">(</span><span style="color: #DD0000">'echo&nbsp;"$foo\n";&nbsp;$bar&nbsp;=&nbsp;$foo&nbsp;.&nbsp;"baz";'</span><span style="color: #007700">);<br />echo&nbsp;</span><span style="color: #DD0000">"</span><span style="color: #007700">{</span><span style="color: #0000BB">$sandbox</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">bar</span><span style="color: #007700">}</span><span style="color: #DD0000">\n"</span><span style="color: #007700">;<br />if&nbsp;(isset(</span><span style="color: #0000BB">$sandbox</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">foo</span><span style="color: #007700">))&nbsp;unset(</span><span style="color: #0000BB">$sandbox</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">foo</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$sandbox</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">eval</span><span style="color: #007700">(</span><span style="color: #DD0000">'var_dump(isset($foo));'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
   </div>

  </div>
  <p class="para">以上例程会输出：</p>
  <div class="example-contents screen">
<div class="cdata"><pre>
bar
barbaz
bool(false)
</pre></div>
  </div>
 </div>


 <div class="refsect1 functions" id="refsect1-runkit.sandbox-functions">
  <h3 class="title">Calling PHP Functions</h3>
  <p class="para">
   Any function defined within the sandbox may be called as
   a method on the sandbox object.  This also includes a few
   pseudo-function language constructs:  <span class="function"><a href="function.eval.html" class="function">eval()</a></span>,
   <span class="function"><a href="function.include.html" class="function">include</a></span>, <span class="function"><a href="function.include-once.html" class="function">include_once</a></span>,
   <span class="function"><a href="function.require.html" class="function">require</a></span>, <span class="function"><a href="function.require-once.html" class="function">require_once</a></span>,
   <span class="function"><a href="function.echo.html" class="function">echo</a></span>, <span class="function"><a href="function.print.html" class="function">print</a></span>,
   <span class="function"><a href="function.die.html" class="function">die()</a></span>, and <span class="function"><a href="function.exit.html" class="function">exit()</a></span>.
  </p>

  <div class="example" id="example-504">
   <p><strong>Example #3 Calling sandbox functions</strong></p>
   <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br />$sandbox&nbsp;</span><span style="color: #007700">=&nbsp;new&nbsp;</span><span style="color: #0000BB">Runkit_Sandbox</span><span style="color: #007700">();<br /><br />echo&nbsp;</span><span style="color: #0000BB">$sandbox</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">str_replace</span><span style="color: #007700">(</span><span style="color: #DD0000">'a'</span><span style="color: #007700">,</span><span style="color: #DD0000">'f'</span><span style="color: #007700">,</span><span style="color: #DD0000">'abc'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
   </div>

  </div>
  <p class="para">以上例程会输出：</p>
  <div class="example-contents screen">
<div class="cdata"><pre>
fbc
</pre></div>
  </div>

  <p class="para">
   When passing arguments to a sandbox function, the arguments
   are taken from the outer instance of PHP.  If you wish to pass
   arguments from the sandbox&#039;s scope, be sure to access them as
   properties of the sandbox object as illustrated above.
  </p>

  <div class="example" id="example-505">
   <p><strong>Example #4 Passing arguments to sandbox functions</strong></p>
   <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br />$sandbox&nbsp;</span><span style="color: #007700">=&nbsp;new&nbsp;</span><span style="color: #0000BB">Runkit_Sandbox</span><span style="color: #007700">();<br /><br /></span><span style="color: #0000BB">$foo&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #DD0000">'bar'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$sandbox</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">foo&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #DD0000">'baz'</span><span style="color: #007700">;<br />echo&nbsp;</span><span style="color: #0000BB">$sandbox</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">str_replace</span><span style="color: #007700">(</span><span style="color: #DD0000">'a'</span><span style="color: #007700">,</span><span style="color: #0000BB">$foo</span><span style="color: #007700">,</span><span style="color: #DD0000">'a'</span><span style="color: #007700">);<br />echo&nbsp;</span><span style="color: #0000BB">$sandbox</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">str_replace</span><span style="color: #007700">(</span><span style="color: #DD0000">'a'</span><span style="color: #007700">,</span><span style="color: #0000BB">$sandbox</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">foo</span><span style="color: #007700">,</span><span style="color: #DD0000">'a'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
   </div>

  </div>
  <p class="para">以上例程会输出：</p>
  <div class="example-contents screen">
<div class="cdata"><pre>
bar
baz
</pre></div>
  </div>
 </div>


 <div class="refsect1 settings" id="refsect1-runkit.sandbox-settings">
  <h3 class="title">Changing Sandbox Settings</h3>
  <p class="para">
   As of runkit version 0.5, certain Sandbox settings may
   be modified on the fly using ArrayAccess syntax.
   Some settings, such as <em><code class="parameter">active</code></em>
   are read-only and meant to provide status information.
   Other settings, such as <em><code class="parameter">output_handler</code></em>
   may be set and read much like a normal array offset.
   Future settings may be write-only, however no such
   settings currently exist.
  </p>

  <p class="para">
   <table class="doctable table">
    <caption><strong>Sandbox Settings / Status Indicators</strong></caption>
    
     <thead>
      <tr>
       <th>Setting</th>
       <th>Type</th>
       <th>Purpose</th>
       <th>Default</th>
      </tr>

     </thead>

     <tbody class="tbody">
      <tr>
       <td><em>active</em></td>
       <td><span class="type"><a href="language.types.boolean.html" class="type Boolean">Boolean</a></span> (Read Only)</td>
       <td>
        <strong><code>TRUE</code></strong> if the Sandbox is still in a usable state,
        <strong><code>FALSE</code></strong> if the request is in bailout due to a
        call to die(), exit(), or because of a fatal
        error condition.
       </td>
       <td><strong><code>TRUE</code></strong> (Initial)</td>
      </tr>

      <tr>
       <td><em>output_handler</em></td>
       <td><span class="type"><a href="language.pseudo-types.html#language.types.callback" class="type Callback">Callback</a></span></td>
       <td>
        When set to a valid callback, all output generated
        by the Sandbox instance will be processed through
        the named function.
        Sandbox output handlers follow the same calling
        conventions as the system-wide output handler.
       </td>
       <td>None</td>
      </tr>

      <tr>
       <td><em>parent_access</em></td>
       <td><span class="type"><a href="language.types.boolean.html" class="type Boolean">Boolean</a></span></td>
       <td>
        May the sandbox use instances of the
        <strong class="classname">Runkit_Sandbox_Parent</strong> class?
        Must be enabled for other
        <strong class="classname">Runkit_Sandbox_Parent</strong>
        related settings to work.
       </td>
       <td><strong><code>FALSE</code></strong></td>
      </tr>

      <tr>
       <td><em>parent_read</em></td>
       <td><span class="type"><a href="language.types.boolean.html" class="type Boolean">Boolean</a></span></td>
       <td>
        May the sandbox read variables in its parent&#039;s context?
       </td>
       <td><strong><code>FALSE</code></strong></td>
      </tr>

      <tr>
       <td><em>parent_write</em></td>
       <td><span class="type"><a href="language.types.boolean.html" class="type Boolean">Boolean</a></span></td>
       <td>
        May the sandbox modify variables in its parent&#039;s context?
       </td>
       <td><strong><code>FALSE</code></strong></td>
      </tr>

      <tr>
       <td><em>parent_eval</em></td>
       <td><span class="type"><a href="language.types.boolean.html" class="type Boolean">Boolean</a></span></td>
       <td>
        May the sandbox evaluate arbitrary code in its
        parent&#039;s context? <em class="emphasis">DANGEROUS</em>
       </td>
       <td><strong><code>FALSE</code></strong></td>
      </tr>

      <tr>
       <td><em>parent_include</em></td>
       <td><span class="type"><a href="language.types.boolean.html" class="type Boolean">Boolean</a></span></td>
       <td>
        May the sandbox include php code files in its
        parent&#039;s context? <em class="emphasis">DANGEROUS</em>
       </td>
       <td><strong><code>FALSE</code></strong></td>
      </tr>

      <tr>
       <td><em>parent_echo</em></td>
       <td><span class="type"><a href="language.types.boolean.html" class="type Boolean">Boolean</a></span></td>
       <td>
        May the sandbox echo data in its parent&#039;s context
        effectively bypassing its own output_handler?
       </td>
       <td><strong><code>FALSE</code></strong></td>
      </tr>

      <tr>
       <td><em>parent_call</em></td>
       <td><span class="type"><a href="language.types.boolean.html" class="type Boolean">Boolean</a></span></td>
       <td>
        May the sandbox call functions in its
        parent&#039;s context?
       </td>
       <td><strong><code>FALSE</code></strong></td>
      </tr>

      <tr>
       <td><em>parent_die</em></td>
       <td><span class="type"><a href="language.types.boolean.html" class="type Boolean">Boolean</a></span></td>
       <td>
        May the sandbox kill its own parent? (And thus itself)
       </td>
       <td><strong><code>FALSE</code></strong></td>
      </tr>

      <tr>
       <td><em>parent_scope</em></td>
       <td><span class="type"><a href="language.types.integer.html" class="type Integer">Integer</a></span></td>
       <td>
        What scope will parental property access look at?
        0 == Global scope, 1 == Calling scope,
        2 == Scope preceding calling scope,
        3 == The scope before that, etc..., etc...
       </td>
       <td><em>0</em> (Global)</td>
      </tr>

      <tr>
       <td><em>parent_scope</em></td>
       <td><span class="type"><a href="language.types.string.html" class="type String">String</a></span></td>
       <td>
        When <em>parent_scope</em> is set to
        a string value, it refers to a named array variable
        in the global scope.  If the named variable does not
        exist at the time of access it will be created as an
        empty array.  If the variable exists but it not an array,
        a dummy array will be created containing a reference
        to the named global variable.
       </td>
       <td class="empty">&nbsp;</td>
      </tr>

     </tbody>
    
   </table>

  </p>
 </div>


</div><hr /><div class="manualnavbar" style="text-align: center;">
 <div class="prev" style="text-align: left; float: left;"><a href="ref.runkit.html">runkit 函数</a></div>
 <div class="next" style="text-align: right; float: right;"><a href="runkit.sandbox-parent.html">Runkit_Sandbox_Parent</a></div>
 <div class="up"><a href="ref.runkit.html">runkit 函数</a></div>
 <div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
